The AD Object Picker AS component

Displays a dialog that allows the caller to select one or many objects from Active Directory.

When to use

This component is typically used in an Intranet where there is a need to select one or more object from the Active Directory.

Details

This is an example of how the component might look when placed on a page.

When the user presses the Select button the follwing modal dialog shows up.

When the use selects one or more users the dialog closes and a the selection (as an Xml document) is stored in the hidden textbox (id=ADObjectPickerDisplayStorage). This selection is the used to reload the selecton made previously when a user returns to the same page.

The selection, which is in the xml format, is stored in a hidden INPUT field that can be accessed by a programmer on the server side when the data has been submitted or on the client side by requesting the field name in the HTML dom. When the dialog loads this xml is used to pre-load the dialog with AD objects but no verification is made to verify the validity of this pre-selection. To use custom parts of this detailed xml document, an advanced developer can have Content Studio to execute a client-side JScript delegate function to be able to save parts of the data in a custom field that can be submitted along with the standard data.
The list below specifies the fields are always part of the selection xml, in addition to these fields a developer can request additional fields by specifying their names in the Extra Fields parameter.

type

The type is not a part of the Active Directory schema and indicates the type of object selected ex. user or contact

cn

The common name field that is used to uniquely identify the object within a OU (Organizational Unit)

samaccountname

The name of the object in the standard NTLM-format (DOMAIN\NAME) ex. TEKNIKHUSET.SE\jimwhit

samnetbionsname

The name of the domain where the object belong. This name is old netBios name opposed to the DNS name used by Active Directory

adspath

The LDAP path to the object, ex. LDAP://CS=Jimmy White,OU=Developers,DC=teknikhuset,DC=com.

sid

The object's security identifier in the standard SDL lanugage (ex. S-1-5-21-45243215-62745-12415426-4231423-1009) Not all objects, such as contacts, has any value in this field.

trustee

The trustee field is not a part of the AD schema - it is just a combination of the cn and samnetbios\samaccount fields ex. "White Jimmy (TEKNIKHUSET.SE\jimwhit)"

The selection has the follwing Xml syntax:

<root>
    <list>
    <object type="user" 
            cn="Jimmy White" 
            sid="S-1-5-21-45243215-62745-12415426-4231423-1009" 
            adspath="LDAP://CN=Jimmy White,OU=Development,DC=teknikhuset,DC=com" 
            samaccountname="JIMWHIT" 
            domainnetbiosname="TEKNIKHUSET.SE" 
            trusteename="Jimmy White (TEKNIKHUSET.SE\JIMWHIT)"/>
    </list>
    <!-- more objects might follow -->
</root>

Activate Button text

The text displayed in the button whose click event awakes the select dialog. This button is created automatically and is EPT aware.

Button class

Optional class name that controls the visual apperance of the selection button.

Button attributes

Optional attributes for the button that awakes the dialog. This data must be written as inline HTML code valid for an BUTTON element.

Delete button text

The text displayed in the button that clears out any previous selection. This button is created automatically and is EPT aware.

Delete button class

Optional class name that controls the visual apperance of the delete button.

Delete button attributes

Optional attributes for the button that clears out any previous selection. This data must be written as inline HTML code valid for an BUTTON element. If you do not want this button to appear you can hide it by using the display:none style attribute.

Display field name

The name and ID of the information input field that displays the selection from the dialog. You must name this field in order to get this component working. Additionaly you should ensure that the name is unique on the actual page. By default this field shows the names (cn) of the selected objects but an advanced developer can override this behavour by using the AfterSelection delegate functionality.

Display field class

Optional class name that controls the visual apperance of the field that displays the callers selection.

Display field attributes

Optional attributes for the field that displays the selection done. This data must be written as inline HTML code valid for an INPUT element. To hide this field you can use the display:none directive in the style attribute.

Dialog visual behaviour

Dialog title

The text in the dialog's title bar.

Dialog width

The width of the dialog. Recommended width is 600 for multi select dialogs and 300 for single selection dialogs

Dialog height

The height of the dialog. Recommended value is 400

Possible search filters

These alternatives determines which "Search among" alternatives will be
available to the caller. At least one alternative must be selected.

Search among Users

Displays the alternative Users among the alternatives that the caller can choose from. This name is localized.

Search among Security Groups

Displays the alternative Groups among the alternatives that the caller can choose from. This name is localized.

Search among Users and Security Groups

Displays the alternative Users and Groups among the alternatives that the caller can choose from. This name is localized.

Search among Computers

Displays the alternative Computers among the alternatives that the caller can choose from. This name is localized.

Search among Contacts

Displays the alternative Contacts among the alternatives caller can choose from. This name is localized.

Dialog general behaviour

Use multi selection

Allows the caller to select more than one object.

LDAP path

The LDAP path to use. This parameter can be an empty string to use the default first site in the Active Directory. The search will look for objects matching the search criteria in all objects below this point. For a more fine grained control you can supply the Organizational Unit to start searching from ex. LDAP://OU=Development Unit,DC=teknikhuset,DC=com.

Wildcard behaviour

Regulates how the dialog automatically adds wildcards (*) to the entrered search string when performing the actual search. Note that wildcards can substantially decrease search performance.

Extra fields

A list of extra fields to return. Individual item are separated by a comma ex. "mail,displayName,mobile". These fields must exist in the Active Directory schema, if not, error -2147467259 (Unspecified error) will be generated.

Advanced

Initial search criteria

A search criteria that acts as the initial search string when the dialog loads. If this parameter is an empty string no initial search is performed. In single select mode a successful search overrides the passed in pre-selected users.

After selection delegate

If this parameter is specified this is a name, without parantheses or arguments, of a JScript funtion that executes after that the dialog has been closed. This delegate function, which have no return value, must be created by the developer and takes 2 arguments in the order specified below:

• A MSXML DOM object that is the selection made by the caller.
• A boolean that is set to true if the dialog was cancelled.

A developer can use this delegate to make her own logic after that a selection is made i.e save parts of the selection to a field of her own.

The follwing sample shows a delagate function that writes the Xml document just selected by the user into an ordinary DIV-element given the id selection. The code block is preferably placed in the HEAD section of the document.

<script type="text/javascript">
<!--
function displaySelection(dom, cancelled)
{
	if(cancelled)
		return;
	selection.innerText = dom.xml;
}
-->
</script>

To have ADObjectPicker to automatically call this script function you need to enter the name of the function, displaySelection, into the After selection delegate parameter.

After delete selection delegate

If this parameter is specified this is a name, without parantheses or arguments, of a JScript funtion that executes after that the caller has deleted the previous selection. This delegate function must be created by the developer and takes no arguments and has no return value. A developer can use this delegate to make her own logic after that the selection has been cleared.

The idea of this parameter is the same as the former but it is called when the selection is deleted and the delegate does not take any paramters.

Since it uses the Microsoft DOM parser it can only be used in Microsoft Internet Explorer on the PC platform.

ADObjectPicker can only be used in a HTML document with Meta Data, thus it is not available in include documents.
This component requires that the Web server is an Active Directory member server. All search operations runs in the context of the Content Studio runtime account and for this reason users do not need to be Active Directory members.